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