# bnb / bnb-macros
A fast, **owned bit-aware** binary codec, integer-backed, that collapses the
capabilities of a bitfield/int/enum stack (`modular-bitfield(-msb)`,
`bitfield-struct`, `bitbybit`, `arbitrary-int`, `num_enum`) plus a declarative codec
**modeled on `binrw`** into one crate. The unified `#[bin]` attribute is the
whole-message front-end
(magic/count/ctx/map/if/calc·temp/reserved/positioning/validate + a
`Source`/`SeekSource`/`BufSource`/`SeekReader` I/O ladder, opt-in `bytes`). The codec
is entirely in-house — `binrw` is an inspiration, not a dependency (see
`ACKNOWLEDGMENTS.md`); `DESIGN.md` has the design rationale.
> Canonical agent-guidance file for this crate; `CLAUDE.md` is a symlink to it, and
> the repo-root `README.md` is the user-facing overview.
>
> **Published as `bitsandbytes` / `bitsandbytes-macros`; imported as `bnb` / `bnb_macros`**
> (via `[lib] name`). Downstream: `bnb = { package = "bitsandbytes" }`, then `use bnb`.
## Two-crate layout (required)
- `bnb/` — runtime lib: `int` (`UInt<T, N>` + `u1..u127`), `field` (the `Bits`
and `Bitfield` traits, `ByteOrder`/`BitOrder`), `error`, `builder`
(`BuilderError`), `bitstream` (the codec runtime: `Source`/`Sink`,
`BitReader`/`BitWriter`, `BitDecode`/`BitEncode`, the I/O ladder, the `bytes`
adapters), `codecs` (ready-made `parse_with`/`write_with` field codecs: sealed
`leb128::Varint`, `cstring`, `prefixed` + the public sealed `CountPrefix`), and
the crate root (re-exports + the `BitEnum` marker trait + `__private` for
generated code).
- `bnb-macros/` — proc-macro crate: `#[bitfield]`, `#[derive(BitEnum)]`,
`#[bitflags]`, `#[derive(BitsBuilder)]` (the `builder` module is shared by the
standalone derive and the `#[bitfield]` intercept), the low-level
`#[derive(BitDecode)]`/`#[derive(BitEncode)]` codec derives, and `#[bin]` (the
unified codec attribute that folds those derives + the builder).
A proc-macro crate cannot also export runtime items, hence the split. Depend only on
the runtime (`bnb = { package = "bitsandbytes" }`); it re-exports the macros, so
downstream never names `bitsandbytes-macros` directly.
## How the `#[bitfield]` macro works (the load-bearing idea)
The macro **cannot** know the numeric width of a field whose type is another
bitfield/enum — those widths live in `<T as Bits>::BITS`, resolved by the
compiler. So `#[bitfield]` emits **const expressions** (`<T as Bits>::BITS`,
cumulative sums, offset/mask arithmetic) that the compiler evaluates during
const-eval; the generated accessors then shift/mask the single backing integer.
If you change the macro, keep that invariant — don't try to compute widths in
the proc-macro.
- **Accessors are `const fn`, so they never call `Bits` methods** (trait calls
aren't const on stable; associated consts like `BITS` are fine). Value
conversions go through the const dispatch (`lib.rs::const_from_bits`/
`const_into_bits`): `bool`/primitives inline, everything else via the hidden
inherent `__bnb_from_bits`/`__bnb_into_bits` pair that `UInt` and every
`Bits`-producing macro emit — and the real `Bits` impls **delegate to that
pair** (never duplicate the logic; one deliberate exception: a no-catch-all
`BitEnum`'s *trait* `from_bits` keeps its own match so the runtime decode path
keeps the formatted, value-bearing panic a `const fn` can't express). Don't
emit a trait-method call in accessor position; don't emit a formatted panic in
a `const fn` (literal/`concat!` only). Downstream custom field types get the
pair via `bnb::impl_bits!` — point users there, never at the dunder names.
`#[view]` closures are inlined when the raw type is annotated (or `raw = <ty>`
is given); `dynamic` keeps the runtime closure-call form, `const` asserts
const-ness (fallbacks become errors).
- **Generated structs are `#[repr(transparent)]`** over the backing (bitfields
and bitflags), suppressed if the user writes any `#[repr(...)]` themselves.
Rationale in `DESIGN.md` §3.4–3.5.
- Layout consts: `Name::__bits_w_<field>` / `__bits_off_<field>` /
`__bits_mask_<field>` and `Name::WIDTH` (the inherent impl carries
`#[allow(non_upper_case_globals)]`).
- `bits = msb`: `off = WIDTH - cumulative_including_field`. `bits = lsb`:
`off = cumulative_before_field`. `#[bits(A..=B)]`: absolute (`off = A`).
- A `#[bitfield]` emits `Bits` + `Bitfield` impls (so it nests in another
bitfield and in a `#[bin]` message) using its **declared** byte order, plus
inherent `to_be_bytes`/`to_le_bytes`/`from_be_bytes`/`from_le_bytes`.
- `#[bitfield]` **intercepts `#[derive(Debug)]`** (like `BitsBuilder`, via
`split_outer_attrs`) and emits a custom `Debug` over the *logical* getters
(`version: u4(4), ihl: u4(5)`) instead of letting std derive the opaque
`{ value: 69 }` on the collapsed backing int. A `#[bin]` struct's std `Debug`
then shows nested bitfields decomposed.
- A byte-aligned `BitEnum` *also* gets `num_enum`-parity conversions
(`bitenum.rs::conv_impls`): `From<Enum> for uN` always; `From<uN> for Enum`
when there's a `#[catch_all]` (total) else `TryFrom<uN> for Enum` (errors with
`bnb::UnknownDiscriminant`). So a magic-byte enum needs no hand-written
`From`/round-trip test — the derive is the whole file. (`From`/`TryFrom` are
mutually exclusive per enum, so the std blanket `TryFrom` never collides.) A
sub-byte enum (`u4`) gets none of these — it is meaningful only nested in a
`#[bitfield]`.
## `#[bitflags]` and `#[derive(BitsBuilder)]`
- **`#[bitflags(uN)]`** takes `bool` fields (an attribute macro needs a valid
struct, and a `bool` *is* a 1-bit flag); each auto-assigns a bit by position
(LSB-first), or `#[flag(N)]` pins it. It generates UPPERCASE consts, set
operators, `contains`/`iter`, per-flag `fin()`/`with_fin`/`set_fin`, and
`Bits`/`Bitfield` impls — so a flag set nests in a `#[bitfield]`. `from_bits`
**retains** unknown bits (dual-use); `from_bits_truncate` drops them.
- **`#[derive(BitsBuilder)]`** — required-by-default; `build() -> Result<_, BuilderError>`
errors on the first unset field; `#[builder(default)]` / `#[builder(default = expr)]`
opts a field out. **Intercept mechanism (load-bearing):** because `#[bitfield]`
collapses the struct to one integer *before* derives run, a real derive can't
see the logical fields — so `#[bitfield]` itself scans its derive list for
`BitsBuilder` (`split_outer_attrs`), generates the builder from the fields, and
strips the marker. A real `BitsBuilder` derive also exists for **plain**
structs. So: put `#[bitfield(...)]` **above** `#[derive(BitsBuilder, ...)]`.
## `#[bin]` — the unified whole-message codec
`#[bin]` is the crate's flagship: one attribute that
folds the codec (`BitDecode`/`BitEncode`) and the required-by-default builder over
a struct, generating `decode` (cursor over a `Source`), `decode_all`/`decode_iter`/`decode_exact`/
`peek` (slice/`Vec`, layout-baked), `encode`/`to_bytes`, and
`Foo::builder()`. The emitted struct has no hidden fields, so it is also constructible via an
ordinary **struct literal**. It reads/writes fields at **arbitrary bit offsets**, so the same
attribute handles byte-aligned headers and sub-byte frames alike.
- **Codegen model.** `#[bin]` generates the codec **directly** from the full field
list via the shared generators (`gen_decode`/`gen_encode` — the same functions
the bare derives call); it does *not* lower to the derives, because it owns the
emitted struct (drops `temp` fields, strips codec attrs, desugars `count_prefix`)
— a derive cannot re-emit the item. The bare derives
stay usable directly for read/write without the `#[bin]` sugar.
- **Struct-level options:** `read_only` / `write_only` (directional codecs),
`no_builder`, `bits = msb|lsb`, `bytes = big|le` (`big`/`little`),
`allow_byte_aligned`.
- **Struct-level wire mapping (`bin_struct_mapped`):** a *logical* struct serializes via a
separate *wire* type, two forms. **Closure form:** `map = |w: Wire| Self` / `try_map = |w:
Wire| Result<Self, E>` (decode) + `bw_map = |s: &Self| Wire` (encode). **Conversion-trait
form:** `wire = WireType` (needs `From<Wire> for Self` + `From<&Self> for Wire`) / `try_wire =
WireType` (`TryFrom<Wire> for Self`, `Error: Display`) — a clean named home for the transitions,
reusable in-program. It **bypasses the field codec**: the struct's fields are logical data, the
wire type owns the bytes. Both forms delegate to the wire type via the same runtime helpers
(`decode_mapped_msg`/`decode_try_mapped_msg`/`encode_mapped_msg`, passing the closure or
`From::from`/`TryFrom::try_from`), so the ordinary slice surface works at the wire layout.
**No `FixedBitLen` is emitted** (so the wire type may be **variable-length**); to nest a
*fixed*-wire mapped type as a plain field, hand-write `impl FixedBitLen for Self { const BIT_LEN
= <Wire as FixedBitLen>::BIT_LEN; }`. Wire type comes from `wire`/`try_wire` directly, or the
closure param/`bw_map` return. The two forms are mutually exclusive with each other; both reject
`magic`/`ctx`/`validate`/`tag`; struct only (not enums). `read_only`/`write_only` narrow the
direction. See `guide::mapping`, `tests/bin_wire_map.rs`.
- **Per-type codec newtypes (`bin_struct_codec`):** `#[bin(codec = <module>)]` (the module's
`parse`/`write` fns, e.g. `bnb::codecs::leb128`) or `#[bin(codec(parse = <f>, write = <f>))]`
(any fns, turbofish allowed) on a **single-field tuple struct** — the reusable per-type dual
of the per-field `parse_with`/`write_with`. Emits `BitDecode`/`BitEncode` delegating to the
fn pair, the slice entry points (at the newtype's own declared order; a *field* decodes
through the parent's cursor), and `From<Inner> for Self` / `From<Self> for Inner`. **No
`FixedBitLen`** (variable assumed — a fixed codec adds the manual one-liner); embed one in an
otherwise-fixed parent with **`#[brw(variable)]`** on the field (suppresses the parent's
`FixedBitLen` claim). Rejects `magic`/`ctx`/`validate`/`tag` and mixing with wire mapping;
`read_only`/`write_only` narrow (the paren form may then omit the unneeded fn). See
`tests/bin_codec_newtype.rs`.
- **Field directives** (the inherited grammar): `#[br]`/`#[bw]`/`#[brw]` with
`magic`, `count`, `count_prefix` (the length-prefixed count sugar: `#[brw(count_prefix
= u16)]` on a `Vec` desugars to the temp+calc+count triad; any `Bits` prefix type incl.
`uN`; checked at encode — an oversized `len()` is a `BitError`, never a wrapped
prefix; `#[bin]`-only), `ctx`/`args`, `map`/`try_map`, `if`, `calc`/`temp`,
`reserved`/`reserved_with`, `parse_with`/`write_with`, `variable` (`#[brw(variable)]` —
the field's type is a variable-length custom codec; the parent skips `FixedBitLen`),
`pad_before`/`pad_after`/
`align_*`/`seek`/`restore_position`, `dbg`, and `assert(<expr>[, "fmt", args…])`
(a **decode-time guard**, binrw-parity: runs after the field is read + mapped, over
this and earlier fields; fails with `ErrorKind::Convert` + the field name; read-only —
no inverse, encode untouched, so forging stays possible. The explicit opt-in
strictness escape hatch — same rejection family as `magic`/closed enums/`try_map`;
the default parser stays permissive. Struct-level `validate = <path>` remains the
construction-side semantic check.) Positioning amounts
use the `prelude` typed helpers (`4.bits()`, `3.bytes()`).
- **I/O ladder** (`bnb::bitstream`): `Source`/`Sink` (the bit cursors), the
`SeekSource` marker for in-memory buffers, `BufSource<R: Read>` (bounded
retain-and-seek over a forward-only reader), `BitBuf` (push/pull bit-aware in-memory
buffer — pushable, a `SeekSource`, `no_std`; **reclaim is deferred + in place** so a push/pull
loop reuses one alloc, and `BitBuf::bounded(cap)` + `try_push`/`grow` give a fixed alloc-once
footprint, `CapacityError` on overflow), `SeekReader<R: Read + Seek>`, and —
under the opt-in **`bytes`** feature — `BytesReader`/`BytesWriter` for async
framing. Seeking is free cursor math; there is no uniform `Seek` requirement.
- **Opt-in transport helpers (all `std`).** `tokio`: `BinCodec<T>`, a `tokio_util::codec`
Decoder/Encoder over `Framed` (TCP) and `UdpFramed` (UDP). `net`: `MessageStream`
(`read_message`/`write_message` over any `Read + Write`; buffers reads with a `BitBuf` rather than
re-rolling the loop) and `MessageDatagram` (`send_message`/`recv_message` over a `DatagramSocket`)
— both decode in the message's own layout (bound `BitDecode + BitEncode`, to reach `T::LAYOUT`).
**`DatagramSocket` is sealed** via a private `sealed::Sealed` supertrait: `bnb` impls it for
`UdpSocket`/`UnixDatagram` (and `MockDatagramSocket` under `mock`) — a new impl needs
`impl sealed::Sealed` too, so downstream can't (locked by `tests/ui_seal`). `mock` (implies `net`,
for `[dev-dependencies]`): `MockDatagramSocket`/`MockStream` in-memory transports with scripted
inbound, captured outbound, chunked delivery, and error injection (`fail_after`/`fail_next_recv`)
— unit-test `net` code without a socket.
## `no_std` (Option A) — the `std` feature
`bnb` is `no_std` + `alloc`; the default-on **`std`** feature adds everything backed by
`std::io`. **Load-bearing facts when editing the codec/macros:**
- `alloc` is unconditional (`extern crate alloc` in `lib.rs`); use `alloc::{vec::Vec,
string::{String, ToString}}` in the runtime, and emit `#bnb::__private::{Vec, String,
vec}` from the macros — **never `::std::…` inside a `quote!`** (it breaks `no_std`
consumers). Errors impl `core::error::Error`, not `std::error::Error`.
- **Runtime-crate path in generated code is resolved, not hardcoded.** Each macro fn
that emits runtime paths does `let bnb = crate::bnb_path();` and interpolates `#bnb`
(e.g. `#bnb::__private::Vec`) — **never a literal `::bnb` in a `quote!`**. `bnb_path()`
(in `bnb-macros/src/lib.rs`) resolves it via `proc-macro-crate`: the crate is published
as `bitsandbytes` but its lib is named `bnb`, and Cargo links any *non-renamed*
reference (the crate's own tests/doctests/examples, `trybuild`'s temp crates, an
un-aliased `bitsandbytes = "…"` consumer) by the **lib name `bnb`**, but a
`package = "…"`-renamed dep by its **key**. So `crate_name("bitsandbytes")` returning
the package name (or `Itself`, or not-found) ⇒ emit `::bnb`; any other name ⇒ that key.
`lib.rs` carries `extern crate self as bnb;` so `::bnb` resolves inside the lib too.
(If the package is ever renamed, update the `"bitsandbytes"` string in `bnb_path`.)
- Gate behind `#[cfg(feature = "std")]`: the reader/writer adapters (`StreamBitReader`/
`BufSource`/`SeekReader`/`SourceReader`/`SinkWriter`, `as_read`/`as_write`),
`encode_to_writer_with`, `From<std::io::Error>`, and `ErrorKind::Io`.
- **Two encode forms — verbatim vs canonical, selected per call.** `to_bytes` and `bit_encode`
are **verbatim**: they emit exactly what's stored (retained `reserved`, stored non-`temp`
`calc`) — never silently rewriting the caller's bytes, and `decode → to_bytes` is
byte-identical. `to_canonical_bytes` and `canonical_bit_encode` are **canonical**: reserved
→ spec value, `calc` → recomputed, so the result is always spec-compliant. `canonical_bit_encode`
is a **defaulted method on `BitEncode`** (`fn canonical_bit_encode(..) { self.bit_encode(..) }`),
overridden by the derive **only** when a message has a `reserved` or non-`temp` `calc` field
(else verbatim == canonical) — there is no separate `CanonicalEncode` trait. There is **no
canonical decode** — `decode_*` is always verbatim. The same `reserved`/`calc` condition also
generates the inherent `to_canonical_bytes` plus the in-memory helpers
`to_canonical(self) -> Self`, `canonical_diff(&self) -> Vec<&'static str>` (fields differing
from canonical), and `is_canonical(&self) -> bool`. (Sink-writing is the `BitEncode` trait
methods `bit_encode`/`canonical_bit_encode`, not an inherent `encode_into` — that wrapper was
cut as redundant.)
- **The form is chosen per call — there is no carried mode.** The `std`-gated blanket
`EncodeExt::encode(&self, w)` is **unconditionally verbatim** (== `to_bytes`); to write the
canonical form over a writer, normalize first: `value.to_canonical().encode(&mut w)`. `EncodeExt`
is an ext trait — **not** a generated inherent method — because a proc-macro can't see the
consumer's features, so a generated `#[cfg(feature="std")]` would key off the *wrong* crate's flag
(bring it in with `use bnb::prelude::*`). A `reserved`/`calc` message is now an **ordinary
struct** — no injected field — so it supports **struct literals** and **coexists with `serde`
derives** (the old "serde rejects `reserved`/`calc` messages" limitation is gone). Generated,
portable (no `EncodeExt`) methods: `to_bytes` (verbatim) and `to_canonical_bytes` (canonical);
sink-writing is the trait methods on `impl BitEncode { const LAYOUT; fn bit_encode; [fn
canonical_bit_encode when reserved/calc] }`.
- `#[br(dbg)]` is `std`-only (`tracing` is an optional dep enabled by `std`); the
`__private::tracing` re-export is `std`-gated.
### Low-level `#[derive(BitDecode/BitEncode)]` + the right-tool guard
The bare derives are the codec without the builder/`#[bin]` sugar — use them when
you want only read/write. They carry a **right-tool guard (don't remove):** a
const-eval assert (`alignment_guard`, same mechanism as the `#[bitfield]` fill
assert) that **rejects an all-byte-aligned struct** — every field width a multiple
of 8 ⇒ the cursor never leaves byte boundaries ⇒ `#[bin]` is the better tool, and
a sub-byte run that fills one integer wants `#[bitfield]`. The message names those
alternatives. Escape hatch: struct-level `#[bit_stream(allow_byte_aligned)]` (a
helper attr declared by both derives; `#[bin]` always sets it, since a byte-aligned
message is a first-class `#[bin]` use, not a misuse). Proof:
`tests/ui/bitstream_byte_aligned.rs` (reject) + `tests/bitstream_guard.rs`
(override). Grouping is steered by the message + the docs decision table, **not** a
hard rule (a `u4`+`u4` run is legitimately ambiguous; erroring on it would add
confusion, not remove it).
## Gotchas
- A catch-all `#[derive(BitEnum)]` mixes a tuple variant with discriminants;
Rust forbids **explicit** discriminants there without `#[repr(..)]`. For
contiguous-from-0 values the derive's auto-numbering works (drop the `= N`);
only non-contiguous catch-all enums need `#[repr(u8)]` + explicit values.
- A no-`#[catch_all]` `BitEnum` whose variants don't cover its width is a **compile
error** (the infallible `from_bits` codec/getter path would panic on an unknown
discriminant). Add `#[catch_all] Other(uN)` to preserve unknowns (dual-use), or
`#[bit_enum(uN, closed)]` to assert a closed set (then `from_bits` still panics on
an out-of-set value; the checked `TryFrom` rejects it). A fully-covered enum
(e.g. a 2-bit enum with all 4 variants) needs neither.
- Field widths must sum to `<= backing` bits (a generated `const` assert
enforces it). A bitfield's `Bits::BITS` is the **declared total** width, not
the backing width — that's what makes sub-byte nesting (`OpCode` = 5 bits in a
`u8`) compose correctly.
- A fixed-length message implements `FixedBitLen` (its `BIT_LEN` sizes a nested
region); a `count`-bearing (variable-length) message does **not**.
## Testing
**Six layers, by `mod` name** — every test lives in a named module so a level can be run on
its own (`cargo test <layer>` filters by the test's module path). **`unit` and `component`
live inline in the `src/` file they exercise** (they have a logical home next to the code);
`macro_`/`integration`/`e2e`/`property` live in `tests/` (no single src home). Put a new test
in the layer that matches its subject:
- **`unit`** — inline `#[cfg(test)] mod unit` in `src/*.rs`. Pure single-type logic, no macro
expansion, no I/O (`UInt`, `Bits`/`Bitfield`, the `BitReader`/`BitWriter` cursor + `BitError`
Display + the `Source`/`Sink` trait defaults via tiny in-test impls, `error`/`builder`).
- **`component`** — inline `#[cfg(test)] mod component` in `src/*.rs`, next to the adapter it
exercises: `bitstream.rs` for the I/O ladder (`BufSource`/`SeekReader`/`StreamBitReader`/
`BitBuf`/the `bytes` adapters), `net.rs` for the `mock`-driven `Message*` wrappers, `codec.rs`
for the `tokio` `BinCodec`. (`#[bin]` works inside the crate's own test mods via
`extern crate self as bnb`.)
- **`macro_`** — `tests/`, `mod macro_`. One generated surface over a slice (`#[bitfield]` /
`BitEnum` / `bitflags` / `BitsBuilder` / bare derives / each `#[bin]` directive). `macro` is
a keyword, hence `macro_`.
- **`integration`** — `tests/`, `mod integration`. Composed protocol shapes over slices
(DNS/SMB in `protocol_shapes`, the DMR burst).
- **`e2e`** — `tests/`, `mod e2e`. Full transport sessions (`MessageStream`/`MessageDatagram`
round-trips, `tokio` `Framed`/`UdpFramed`).
- **`property`** — `tests/`, `mod property`. `proptest` invariants (`fuzz_roundtrip`).
`tests/compile_fail.rs` (trybuild) is the separate negative/UI harness, outside the layers.
```bash
cargo test # whole workspace (default features)
cargo test unit # one layer at a time (filters by mod name):
cargo test macro_ # unit · macro_ · component · integration · e2e · property
cargo test -p bitsandbytes --features bytes # + the bytes-crate I/O adapters
cargo test -p bitsandbytes --features mock # + net socket helpers, mocks, the sealed-trait UI test
cargo test -p bitsandbytes --features tokio # + the async BinCodec (Framed/UdpFramed)
# Coverage (cargo-llvm-cov): the runtime crate `bnb/src` is 90–100% per file. The macro crate
# reads lower because its diagnostic arms are exercised only by trybuild (separate rustc
# processes llvm-cov can't instrument) — not a true gap; still test real generated paths.
# A host `--no-default-features` build still links std, so the cross target is the
# one that actually fails on a leak.
cargo build --manifest-path bnb/nostd-check/Cargo.toml --target thumbv7em-none-eabi
# MSRV floor (1.85): let-chains are unstable below 1.88 — DON'T use them; verify with:
cargo +1.85.0 check --workspace
```
- Inline tests in `src/*.rs`: `mod unit` (int ranges/conversions, `Bits` impls, the
`BitReader`/`BitWriter` cursor + `BitError`, `error`/`builder`) and `mod component` (the I/O
ladder in `bitstream.rs`, the `mock`-driven wrappers in `net.rs`, the `tokio` `BinCodec` in
`codec.rs`).
- `tests/protocol_shapes.rs` — the **real** DNS `State` (0x1002), nested
`OpCode`/`Flags` positions, catch-all preservation, exhaustive `Op`, SMB
`SecurityMode` (LSB) / `Capabilities` (LE), manual ranges, and the `Bitfield`
seam. Golden byte vectors.
- `tests/comprehensive.rs` — the full bitfield matrix: every backing (u8..u128),
msb/lsb mirroring, all three width forms agreeing, masking/overflow,
partial-width padding, 3-level nesting, byte-order, exhaustive/catch-all/
contract-violation enums (incl. the documented panic for a non-exhaustive
no-catch-all enum), and UInt boundaries + error `Display`.
- `tests/flags.rs` — `#[bitflags]`: consts, set algebra + operators, per-flag
accessors, `iter`, retain vs truncate, nesting in a `#[bitfield]`.
- `tests/builder.rs` — `#[derive(BitsBuilder)]`: required-field errors, `default`
/ `default = expr`, the `#[bitfield]` intercept, and the plain-struct path.
- `tests/bin_*.rs` — the `#[bin]` surface, one concern per file: `bin_macro`
(the fold), `bin_magic`, `bin_count` (+ `bin_count_adversarial`: hostile
`count` — over-count → graceful EOF, `u32::MAX` → no pre-alloc, under-count
→ `TrailingBytes`), `bin_ctx`(+`_layer2`), `bin_map`,
`bin_if`, `bin_calc_temp`, `bin_reserved`, `bin_ignore`, `bin_parse_with`,
`bin_positioning`/`bin_restore_position`, `bin_validate`, `bin_byte_order`
(+ `bin_order_matrix`: the message-level endian × bit-order 2×2),
`bin_fold`. (The low-level I/O-ladder adapter tests — `BufSource`/`SeekReader`/`BitBuf`/the
`bytes` adapters / `as_read`-`as_write` — moved to `src/bitstream.rs`'s `mod component`.)
- `tests/bitstream_*.rs` — the low-level derives/runtime: `bitstream_dmr`(+`_frame`)
(the `108|48|108` DMR burst that motivated bit offsets), `bitstream_nested`,
`bitstream_payload`, `bitstream_bitorder`, `bitstream_builder`, `bitstream_guard`
(the right-tool-guard override). (`bitstream_source`/`_seek`/`_entry`/`_errors` moved to
`src/bitstream.rs`'s `mod component`.)
- Transport `e2e` in `tests/`: `net.rs` (`--features net`, real sockets), `net_mock.rs`
(`--features mock`, mock-stream session + loopback UDP), `codec_tokio.rs` (`--features tokio`,
`Framed`/`UdpFramed` round-trips). The one-call `component` tests for these live inline in
`src/net.rs` and `src/codec.rs`.
- `tests/compile_fail.rs` + `tests/ui/*` — trybuild snapshots proving `#[bin]` /
`#[bitfield]` / derive misuse is rejected with a clear, well-spanned error
(`bin_count_not_fixed`, `bin_ctx_needs_context`, `bin_forward_only_no_seek`,
`bin_if_needs_option`, `bin_map_needs_inverse`, `bin_temp_needs_calc`,
`bin_validate_needs_builder`, `bitfield_range_reversed`,
`bitstream_byte_aligned`). `tests/ui_seal/*` (run under `--features mock`) proves the sealed
`DatagramSocket` rejects a downstream impl. Regenerate with `TRYBUILD=overwrite`.
`#![deny(missing_docs)]` is on (both crates); the `uN` aliases are the one
allowed exception. Keep the public surface fully documented.
## Benchmarks
- `benches/bitfield_bench.rs` (criterion, `Criterion::default()`) measures `bnb`
**against the crates it replaces** — `bitbybit`, `modular-bitfield-msb` (dev-deps,
bench-only) — and a hand-written shift/mask baseline, on an identical DNS-shaped
16-bit field. Result: `bnb` matches `bitbybit`, beats `modular-bitfield`, within
noise of hand-written (pack ~870ps, unpack ~192ps).
- `benches/bitstream_bench.rs` — the `#[bin]`/derive codec throughput.
Run: `cargo bench -p bitsandbytes`.
## Examples
- `enums` — `#[derive(BitEnum)]` in depth: exhaustive, catch-all (the `num_enum`
pattern), nesting, and checked-int error handling.
- `standalone` — building the IPv4 `0x45` byte from the field types directly.
## Scope notes
- Dual-use: `from_raw`/`from_be_bytes` and the parser never validate; `#[catch_all]`
preserves unknown enum values; `#[bin]`'s `validate`/soundness is
**construction-side only** (gates `build()`, leaves decode permissive). Keep
that — never make a parser reject representable input. `validate = path` is also
generated as re-runnable `validate()` / `is_valid()` methods (computed on demand — no
stored "valid" flag, which would go stale on mutation). By convention `validate` checks
**semantic** soundness, not `calc`/`reserved` fields (those are representational, normalized
by `to_canonical_bytes`), so validity holds for the canonical form too; `to_canonical_bytes`
itself stays a pure normalization (compose `validate()` before sending if you need the check).
- The `Bitfield` seam (`to_raw`/`from_raw` + the codec-agnostic trait) is the hook
the `#[bin]` codec builds on; a value type stays codec-agnostic.