Expand description
A const-first, allocation-free, trait-free CBOR codec per RFC 8949.
const-cbor encodes and decodes CBOR data items directly between Rust
values and byte buffers. There is no intermediate value tree, no heap
allocation, no unsafe, no traits, and no dependencies: the crate uses
only core.
§Design
-
const fneverywhere — heads, argument widths, and encoded lengths are computed byconst fns (seeheadandencode), so the compiler folds them away for statically known inputs. Entire encodings can be evaluated entirely at compile time with the panickingput_*helpers:use const_cbor::encode; const ITEM: ([u8; 4], usize) = { let mut buf = [0u8; 4]; let n = encode::consts::put_u64(&mut buf, 42); (buf, n) }; assert_eq!(&ITEM.0[..ITEM.1], &[0x18, 0x2a]); -
Concrete-typed methods — encoding and decoding go through
EncoderandDecoder, which expose one method per CBOR type (u8,i64,str,bytes,array, …). No trait impls are required from users or for user types. -
Zero-copy decoding — text strings and byte strings borrow from the input buffer (
Decoder::str,Decoder::bytes). -
Compact errors — every failure is a single-byte code (
Error,Copy, no formatting machinery).
§Scope
The core supports major types 0–7 with definite lengths, full-width
integers (u8–u64, i8–i64), tags, simple values, booleans,
null/undefined, and — behind the float feature — f16/f32/f64.
Optional features add indefinite lengths (§3.2), raw zero-copy item
handles, incremental decoding, canonical map ordering, diagnostic
rendering, floating-point numbers, bignums (§3.4.3), and strict
deterministic-encoding validation (§4.2) — see the README feature table.
Without the indefinite feature the decoder rejects ai = 31 and the
encoder never produces it.
§Behavior guarantees
| Property | Guarantee |
|---|---|
| Panics | never at runtime; malformed input is always Err(Error) |
| Allocation | never; only core, no allocator touched |
| Unsafe | forbidden at compile time |
| Recursion | none; Decoder::skip uses a fixed 32-entry stack |
| Failure atomicity | failed encoder calls write nothing and keep the cursor |
| Zero-copy | Decoder::str/bytes borrow from the caller’s input |
Non-minimal integer encodings are accepted on input (RFC 8949 §4.2.1 makes preferred form a SHOULD); forms that are actually invalid — reserved additional information, two-byte simples below 32, non-UTF-8 text — are rejected.
Further documentation lives in the repository’s docs/ directory
(behavior.md, guide.md, conformance.md).
§Example: encode then decode
use const_cbor::{Decoder, Encoder};
let mut buf = [0u8; 64];
let mut enc = Encoder::new(&mut buf);
enc.array_len(3).unwrap();
enc.u8(1).unwrap();
enc.i64(-25_000).unwrap();
enc.str("hello").unwrap();
let n = enc.written();
assert_eq!(&buf[..n], &[
0x83, // array(3)
0x01, // 1
0x39, 0x61, 0xa7, // -25000
0x65, b'h', b'e', b'l', b'l', b'o',
]);
let mut dec = Decoder::new(&buf[..n]);
assert_eq!(dec.array_len().unwrap(), 3); // header, then items in order
assert_eq!(dec.u8().unwrap(), 1);
assert_eq!(dec.i64().unwrap(), -25_000);
assert_eq!(dec.str().unwrap(), "hello");
assert!(dec.is_empty());Re-exports§
pub use crate::decode::Decoder;pub use crate::encode::Encoder;pub use crate::error::Error;pub use crate::head::Major;pub use crate::head::Simple;