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