Skip to main content

Crate const_cbor

Crate const_cbor 

Source
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 fn everywhere — heads, argument widths, and encoded lengths are computed by const fns (see head and encode), so the compiler folds them away for statically known inputs. Entire encodings can be evaluated entirely at compile time with the panicking put_* 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 Encoder and Decoder, 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

PropertyGuarantee
Panicsnever at runtime; malformed input is always Err(Error)
Allocationnever; only core, no allocator touched
Unsafeforbidden at compile time
Recursionnone; Decoder::skip uses a fixed 32-entry stack
Failure atomicityfailed encoder calls write nothing and keep the cursor
Zero-copyDecoder::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;

Modules§

decode
CBOR decoding from borrowed input.
encode
CBOR encoding into caller-provided buffers.
error
Compact, allocation-free error codes.
head
The CBOR head: initial byte, major types, and argument encoding.