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, floating-point numbers, bignums (§3.4.3), and strict
44//! deterministic-encoding validation (§4.2) — see the README feature table.
45//! Without the `indefinite` feature the decoder rejects ai = 31 and the
46//! encoder never produces it.
47//!
48//! # Behavior guarantees
49//!
50//! | Property | Guarantee |
51//! |---|---|
52//! | Panics | never at runtime; malformed input is always `Err(Error)` |
53//! | Allocation | never; only `core`, no allocator touched |
54//! | Unsafe | forbidden at compile time |
55//! | Recursion | none; `Decoder::skip` uses a fixed 32-entry stack |
56//! | Failure atomicity | failed encoder calls write nothing and keep the cursor |
57//! | Zero-copy | `Decoder::str`/`bytes` borrow from the caller's input |
58//!
59//! Non-minimal integer encodings are accepted on input (RFC 8949 §4.2.1
60//! makes preferred form a SHOULD); forms that are actually invalid —
61//! reserved additional information, two-byte simples below 32, non-UTF-8
62//! text — are rejected.
63//!
64//! Further documentation lives in the repository's `docs/` directory
65//! (`behavior.md`, `guide.md`, `conformance.md`).
66//!
67//! # Example: encode then decode
68//!
69//! ```
70//! use const_cbor::{Decoder, Encoder};
71//!
72//! let mut buf = [0u8; 64];
73//! let mut enc = Encoder::new(&mut buf);
74//!
75//! enc.array_len(3).unwrap();
76//! enc.u8(1).unwrap();
77//! enc.i64(-25_000).unwrap();
78//! enc.str("hello").unwrap();
79//!
80//! let n = enc.written();
81//! assert_eq!(&buf[..n], &[
82//!     0x83,             // array(3)
83//!     0x01,             // 1
84//!     0x39, 0x61, 0xa7, // -25000
85//!     0x65, b'h', b'e', b'l', b'l', b'o',
86//! ]);
87//!
88//! let mut dec = Decoder::new(&buf[..n]);
89//! assert_eq!(dec.array_len().unwrap(), 3);  // header, then items in order
90//! assert_eq!(dec.u8().unwrap(), 1);
91//! assert_eq!(dec.i64().unwrap(), -25_000);
92//! assert_eq!(dec.str().unwrap(), "hello");
93//! assert!(dec.is_empty());
94//! ```
95
96#![no_std]
97#![forbid(unsafe_code)]
98
99pub mod decode;
100pub mod encode;
101pub mod error;
102pub mod head;
103
104#[cfg(feature = "float")]
105pub mod float;
106
107#[cfg(feature = "indefinite")]
108pub mod indefinite;
109
110#[cfg(feature = "raw")]
111pub mod raw;
112
113#[cfg(feature = "stream")]
114pub mod stream;
115
116#[cfg(feature = "canonical")]
117pub mod canonical;
118
119#[cfg(feature = "bignum")]
120pub mod bignum;
121
122#[cfg(feature = "deterministic")]
123pub mod deterministic;
124
125#[cfg(feature = "diagnostic")]
126pub mod diagnostic;
127
128pub use crate::decode::Decoder;
129pub use crate::encode::Encoder;
130pub use crate::error::Error;
131pub use crate::head::{Major, Simple};