build: adopt edition 2024, bump msrv to 1.85, add docs.rs math

No API changes; merged #2 (checkout v7) and closed #1 (bad MSRV bump).

Author: ajsb85

.github/dependabot.yml

@@ -22,3 +22,7 @@ updates:
       - "github-actions"
     commit-message:
       prefix: "ci"
+    ignore:
+      # The msrv job pins dtolnay/rust-toolchain to the crate's declared MSRV on
+      # purpose; raise it only when bumping rust-version, never automatically.
+      - dependency-name: "dtolnay/rust-toolchain"

.github/workflows/ci.yml

@@ -51,11 +51,11 @@ jobs:
         run: cargo build --no-default-features --target thumbv7em-none-eabihf
 
   msrv:
-    name: minimum supported Rust (1.81)
+    name: minimum supported Rust (1.85)
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: dtolnay/rust-toolchain@1.81.0
+      - uses: dtolnay/rust-toolchain@1.85.0
       - run: cargo build --all-features
 
   conformance:

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.2.0
+
+### Changed
+
+- Adopted **Rust edition 2024**; the minimum supported Rust version is now
+  **1.85** (required by the edition). No API changes.
+- Modernised CI: bumped `actions/checkout` to v7 and pinned the MSRV job's
+  toolchain to Rust 1.85.
+
+### Documentation
+
+- The Cheshire & Baker (1999) overhead bounds now render as math on docs.rs (via
+  KaTeX): the encoded length is at most $n + \lceil n/254 \rceil$ bytes, and
+  `max_encoded_len` / `encoding_overhead` document their closed forms.
+
 ## 1.1.0
 
 ### Added

Cargo.lock

@@ -1,8 +1,8 @@
 [package]
 name = "cobs_codec_rs"
-version = "1.1.0"
-edition = "2021"
-rust-version = "1.81"
+version = "1.2.0"
+edition = "2024"
+rust-version = "1.85"
 description = "Consistent Overhead Byte Stuffing (COBS) and COBS/R codec: no_std, zero-dependency, for zero-free framing of serial and packet byte streams."
 authors = ["Alexander Salas Bastidas <ajsb85@firechip.dev>"]
 license = "MIT"
@@ -13,6 +13,12 @@ readme = "README.md"
 keywords = ["cobs", "serial", "framing", "no-std", "embedded"]
 categories = ["encoding", "embedded", "no-std"]
 
+[package.metadata.docs.rs]
+# Document every feature, and load KaTeX so the overhead math renders. KaTeX is
+# documentation-support JavaScript, which docs.rs permits; it does no tracking.
+all-features = true
+rustdoc-args = ["--html-in-header", "docs/katex-header.html"]
+
 [features]
 default = ["std"]
 # Enables the `*_to_vec` convenience functions and framing that allocate.

Cargo.toml

@@ -38,10 +38,10 @@ USB, TCP and other byte streams — ideal for embedded and robotics protocols.
 
 ```toml
 [dependencies]
-cobs_codec_rs = "1.1"
+cobs_codec_rs = "1.2"
 
 # no_std, no allocator:
-# cobs_codec_rs = { version = "1.1", default-features = false }
+# cobs_codec_rs = { version = "1.2", default-features = false }
 ```
 
 ## Usage
@@ -85,9 +85,15 @@ rx.push(&chunk, |frame| match frame {
 
 ## Overhead
 
-COBS overhead is data-independent: at most `⌈n / 254⌉` extra bytes for `n` input
-bytes (and always ≥ 1). Compare escape-based schemes (PPP/SLIP), whose worst case
-*doubles* the packet.
+COBS overhead is *data-independent*. Encoding an `n`-byte packet produces at most
+
+$$ n + \left\lceil \frac{n}{254} \right\rceil $$
+
+bytes (one extra byte per 254, rounded up), so the overhead is bounded by
+$\left\lceil n/254 \right\rceil$ and is always at least one byte. By contrast,
+escape-based schemes (PPP, SLIP, HDLC) can *double* the packet in the worst case.
+`cobsr` (COBS/R) can reach zero overhead. These bounds are what `max_encoded_len`
+and `encoding_overhead` return.
 
 ## Background
 

README.md

@@ -0,0 +1,31 @@
+<!-- KaTeX math rendering for docs.rs. Renders $…$ / $$…$$ in the docs client-side.
+     This is documentation-support JavaScript (KaTeX), which docs.rs permits; it
+     does no tracking. See https://docs.rs/about/metadata -->
+<link
+  rel="stylesheet"
+  href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.11/katex.min.css"
+  crossorigin="anonymous"
+/>
+<script
+  defer
+  src="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.11/katex.min.js"
+  crossorigin="anonymous"
+></script>
+<script
+  defer
+  src="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.11/contrib/auto-render.min.js"
+  crossorigin="anonymous"
+></script>
+<script>
+  document.addEventListener("DOMContentLoaded", function () {
+    renderMathInElement(document.body, {
+      delimiters: [
+        { left: "$$", right: "$$", display: true },
+        { left: "\\[", right: "\\]", display: true },
+        { left: "$", right: "$", display: false },
+        { left: "\\(", right: "\\)", display: false },
+      ],
+      throwOnError: false,
+    });
+  });
+</script>

docs/katex-header.html

@@ -7,7 +7,7 @@
 //! allocating (usable in pure `no_std`); [`FrameDecoder`] (behind the `alloc`
 //! feature) does the same into owned [`Vec`]s.
 
-use crate::{cobs, DecodeError, DELIMITER};
+use crate::{DELIMITER, DecodeError, cobs};
 
 #[cfg(feature = "alloc")]
 use crate::cobsr;

src/framing.rs

@@ -37,6 +37,31 @@
 //! assert_eq!(&buf[..n], &[0x02, 0x11, 0x02, 0x22]);
 //! ```
 //!
+//! # Encoding overhead
+//!
+//! COBS has a *tight, data-independent* bound on overhead. Encoding an $n$-byte
+//! packet yields at most
+//!
+//! $$ n + \left\lceil \frac{n}{254} \right\rceil $$
+//!
+//! bytes (one extra byte per 254, rounded up), so the overhead $o(n)$ obeys
+//!
+//! $$ 1 \le o(n) \le \left\lceil \frac{n}{254} \right\rceil \quad (n \ge 1) $$
+//!
+//! and [`max_encoded_len`] and [`encoding_overhead`] return exactly these
+//! worst-case bounds. By contrast, escape-based framing (PPP, SLIP, HDLC) can
+//! *double* a packet in the worst case, an overhead of up to $n$ bytes, because
+//! any byte may need escaping.
+//!
+//! The bound follows from the block structure: COBS emits *blocks*, each a
+//! *code byte* $c$ followed by $c - 1$ non-zero data bytes. A code $c \lt 255$
+//! stands for those bytes then an implicit zero; $c = 255$ carries a full run of
+//! $254$ non-zero bytes (see [`MAX_BLOCK_LEN`]) with no trailing zero. At most
+//! one code byte is spent per 254 data bytes, so an $n$-byte packet needs at
+//! most $\left\lceil \frac{n}{254} \right\rceil$ of them. [`cobsr`] (COBS/R)
+//! drops the final code byte when the last data byte can stand in for it,
+//! reaching a best case of *zero* overhead.
+//!
 //! See "Consistent Overhead Byte Stuffing" by Stuart Cheshire and Mary Baker,
 //! IEEE/ACM Transactions on Networking, Vol. 7, No. 2, April 1999.
 
@@ -63,7 +88,9 @@ pub const MAX_BLOCK_LEN: usize = 254;
 /// when encoding a message of `source_len` bytes.
 ///
 /// COBS adds at most one byte per 254 bytes of input (rounded up), and at least
-/// one byte for any message including the empty one.
+/// one byte for any message including the empty one. In closed form this is
+/// $\lceil n/254 \rceil$ for a non-empty message of $n$ bytes, and $1$ for the
+/// empty message.
 ///
 /// ```
 /// use cobs_codec_rs::encoding_overhead;
@@ -82,7 +109,8 @@ pub const fn encoding_overhead(source_len: usize) -> usize {
 
 /// Returns the maximum possible length, in bytes, of the COBS (or COBS/R)
 /// encoding of a message of `source_len` bytes. Useful for sizing an encode
-/// buffer.
+/// buffer. For a message of $n$ bytes this is $n + \lceil n/254 \rceil$ (and
+/// $1$ when $n = 0$).
 ///
 /// ```
 /// use cobs_codec_rs::max_encoded_len;

src/lib.rs

@@ -3,7 +3,7 @@
 #![allow(clippy::pedantic, missing_docs)]
 
 use cobs_codec_rs::framing::StreamDecoder;
-use cobs_codec_rs::{cobs, cobsr, max_encoded_len, DecodeError};
+use cobs_codec_rs::{DecodeError, cobs, cobsr, max_encoded_len};
 
 /// Tiny deterministic xorshift PRNG (keeps the crate dependency-free).
 struct Rng(u64);
@@ -193,9 +193,10 @@ fn stream_decoder_signals_output_too_small() {
             errs.push(e);
         }
     });
-    assert!(errs
-        .iter()
-        .any(|e| matches!(e, DecodeError::OutputTooSmall)));
+    assert!(
+        errs.iter()
+            .any(|e| matches!(e, DecodeError::OutputTooSmall))
+    );
 }
 
 #[test]