cbor_core/lib.rs
1#![forbid(unsafe_code)]
2
3//! Deterministic CBOR encoder and decoder following the
4//! [CBOR::Core](https://www.ietf.org/archive/id/draft-rundgren-cbor-core-25.html)
5//! profile (`draft-rundgren-cbor-core-25`).
6//!
7//! This crate works with CBOR as an owned data structure rather than as a
8//! serialization layer. Values can be constructed, inspected, modified, and
9//! round-tripped through their canonical byte encoding.
10//!
11//! # Types
12//!
13//! [`Value`] is the central type and a good starting point. It represents
14//! any CBOR data item and provides constructors, accessors, encoding, and
15//! decoding.
16//!
17//! | Type | Role |
18//! |------|------|
19//! | [`Value`] | Any CBOR data item. Start here. |
20//! | [`SimpleValue`] | CBOR simple value (`null`, `true`, `false`, 0-255). |
21//! | [`DataType`] | Classification of a value for type-level dispatch. |
22//! | [`Error`] | All errors produced by this crate. |
23//!
24//! The following types are helpers that appear in `From`/`Into` bounds
25//! and are rarely used directly:
26//!
27//! | Type | Role |
28//! |------|------|
29//! | [`Array`] | Wrapper around `Vec<Value>` for flexible array construction. |
30//! | [`Map`] | Wrapper around `BTreeMap<Value, Value>` for flexible map construction. |
31//! | [`Float`] | IEEE 754 float stored in shortest CBOR form (f16, f32, or f64). |
32//! | [`DateTime`] | Validated ISO 8601 UTC string for tag 0 construction. |
33//! | [`EpochTime`] | Validated numeric epoch time for tag 1 construction. |
34//!
35//! # Quick start
36//!
37//! ```
38//! use cbor_core::{Value, array, map};
39//!
40//! // Build a value
41//! let value = map! {
42//! 1 => "hello",
43//! 2 => array![10, 20, 30],
44//! };
45//!
46//! // Encode to bytes and decode back
47//! let bytes = value.encode();
48//! let decoded = Value::decode(&bytes).unwrap();
49//! assert_eq!(value, decoded);
50//!
51//! // Access inner data
52//! let greeting = decoded[1].as_str().unwrap();
53//! assert_eq!(greeting, "hello");
54//! ```
55//!
56//! # Encoding rules
57//!
58//! All encoding is deterministic: integers and floats use their shortest
59//! representation, and map keys are sorted in CBOR canonical order. The
60//! decoder rejects non-canonical input.
61//!
62//! NaN values, including signaling NaNs and custom payloads, are preserved
63//! through encode/decode round-trips. Conversion between float widths uses
64//! bit-level manipulation to avoid hardware NaN canonicalization.
65
66#[cfg(feature = "num-bigint")]
67mod ext_num_bigint;
68
69mod array;
70mod consts;
71mod data_type;
72mod date_time;
73mod epoch_time;
74mod error;
75mod float;
76mod integer;
77mod iso3339;
78mod macros;
79mod map;
80mod simple_value;
81mod value;
82
83pub use array::Array;
84pub use data_type::DataType;
85pub use date_time::DateTime;
86pub use epoch_time::EpochTime;
87pub use error::{Error, Result};
88pub use float::Float;
89pub use map::Map;
90pub use simple_value::SimpleValue;
91pub use value::Value;
92
93use consts::*;
94use integer::*;
95
96#[cfg(test)]
97mod tests;