Skip to main content

const_cbor/
lib.rs

1//! A const-first, allocation-free, trait-free CBOR codec per RFC 8949.
2//!
3//! `const-cbor` encodes and decodes CBOR data items directly between Rust
4//! values and byte buffers. There is no intermediate value tree, no heap
5//! allocation, no `unsafe`, no traits, and no dependencies: the crate uses
6//! only `core`.
7//!
8//! # Design
9//!
10//! * **`const fn` everywhere** — heads, argument widths, and encoded lengths
11//!   are computed by `const fn`s (see [`head`] and [`encode`]), so the
12//!   compiler folds them away for statically known inputs. Entire encodings
13//!   can be evaluated entirely at compile time with the panicking `put_*`
14//!   helpers:
15//!
16//!   ```
17//!   use const_cbor::encode;
18//!
19//!   const ITEM: ([u8; 4], usize) = {
20//!       let mut buf = [0u8; 4];
21//!       let n = encode::consts::put_u64(&mut buf, 42);
22//!       (buf, n)
23//!   };
24//!   assert_eq!(&ITEM.0[..ITEM.1], &[0x18, 0x2a]);
25//!   ```
26//!
27//! * **Concrete-typed methods** — encoding and decoding go through
28//!   [`Encoder`] and [`Decoder`], which expose one method per CBOR type
29//!   (`u8`, `i64`, `str`, `bytes`, `array`, …). No trait impls are required
30//!   from users or for user types.
31//! * **Zero-copy decoding** — text strings and byte strings borrow from the
32//!   input buffer ([`Decoder::str`], [`Decoder::bytes`]).
33//! * **Compact errors** — every failure is a single-byte code ([`Error`],
34//!   `Copy`, no formatting machinery).
35//!
36//! # Scope
37//!
38//! The core supports major types 0–7 with definite lengths, full-width
39//! integers (`u8`–`u64`, `i8`–`i64`), tags, simple values, booleans,
40//! null/undefined, and — behind the `float` feature — f16/f32/f64.
41//! Optional features add indefinite lengths (§3.2), raw zero-copy item
42//! handles, incremental decoding, canonical map ordering, diagnostic
43//! rendering, and floating-point numbers — see the README feature table.
44//! Without the `indefinite` feature the decoder rejects ai = 31 and the
45//! encoder never produces it.
46//!
47//! # Behavior guarantees
48//!
49//! | Property | Guarantee |
50//! |---|---|
51//! | Panics | never at runtime; malformed input is always `Err(Error)` |
52//! | Allocation | never; only `core`, no allocator touched |
53//! | Unsafe | forbidden at compile time |
54//! | Recursion | none; `Decoder::skip` uses a fixed 32-entry stack |
55//! | Failure atomicity | failed encoder calls write nothing and keep the cursor |
56//! | Zero-copy | `Decoder::str`/`bytes` borrow from the caller's input |
57//!
58//! Non-minimal integer encodings are accepted on input (RFC 8949 §4.2.1
59//! makes preferred form a SHOULD); forms that are actually invalid —
60//! reserved additional information, two-byte simples below 32, non-UTF-8
61//! text — are rejected.
62//!
63//! Further documentation lives in the repository's `docs/` directory
64//! (`behavior.md`, `guide.md`, `conformance.md`).
65//!
66//! # Example: encode then decode
67//!
68//! ```
69//! use const_cbor::{Decoder, Encoder};
70//!
71//! let mut buf = [0u8; 64];
72//! let mut enc = Encoder::new(&mut buf);
73//!
74//! enc.array_len(3).unwrap();
75//! enc.u8(1).unwrap();
76//! enc.i64(-25_000).unwrap();
77//! enc.str("hello").unwrap();
78//!
79//! let n = enc.written();
80//! assert_eq!(&buf[..n], &[
81//!     0x83,             // array(3)
82//!     0x01,             // 1
83//!     0x39, 0x61, 0xa7, // -25000
84//!     0x65, b'h', b'e', b'l', b'l', b'o',
85//! ]);
86//!
87//! let mut dec = Decoder::new(&buf[..n]);
88//! assert_eq!(dec.array_len().unwrap(), 3);  // header, then items in order
89//! assert_eq!(dec.u8().unwrap(), 1);
90//! assert_eq!(dec.i64().unwrap(), -25_000);
91//! assert_eq!(dec.str().unwrap(), "hello");
92//! assert!(dec.is_empty());
93//! ```
94
95#![no_std]
96#![forbid(unsafe_code)]
97
98pub mod decode;
99pub mod encode;
100pub mod error;
101pub mod head;
102
103#[cfg(feature = "float")]
104pub mod float;
105
106#[cfg(feature = "indefinite")]
107pub mod indefinite;
108
109#[cfg(feature = "raw")]
110pub mod raw;
111
112#[cfg(feature = "stream")]
113pub mod stream;
114
115#[cfg(feature = "canonical")]
116pub mod canonical;
117
118#[cfg(feature = "diagnostic")]
119pub mod diagnostic;
120
121pub use crate::decode::Decoder;
122pub use crate::encode::Encoder;
123pub use crate::error::Error;
124pub use crate::head::{Major, Simple};