deser_msgpack/lib.rs
1//! Parse and serialize [MessagePack](https://msgpack.org/) compatible with
2//! deser.
3//!
4//! ```rust
5//! let bytes = deser_msgpack::to_vec(&vec![1u64, 2, 3, 4]).unwrap();
6//! assert_eq!(bytes, [0x94, 0x01, 0x02, 0x03, 0x04]);
7//! let vec: Vec<u64> = deser_msgpack::from_slice(&bytes).unwrap();
8//! assert_eq!(vec, [1, 2, 3, 4]);
9//! ```
10//!
11//! # Data Model
12//!
13//! The deser data model maps onto MessagePack as follows:
14//!
15//! | deser | MessagePack |
16//! |-------------------------|-----------------------------------------------|
17//! | `Null` | nil |
18//! | `Bool` | false / true |
19//! | `U64`, `I64` | integers |
20//! | `u128`, `i128` | integers (if they fit into 64 bits) |
21//! | [`Timestamp`] | the timestamp extension (type `-1`) |
22//! | `F32` | float 32 |
23//! | `F64` | float 64 |
24//! | `Str`, `Char` | str |
25//! | `Bytes` | bin |
26//! | maps and sequences | maps and arrays |
27//! | [`Ext`] | other extensions |
28//!
29//! Integers and lengths are written in their shortest form. Floats keep
30//! their precision. Other extension values (such as
31//! [`Datetime`](deser_core::ext::Datetime) or [`Uuid`](deser_core::ext::Uuid))
32//! are written as their fallback, which usually is a string. Integers
33//! which do not fit into 64 bits cannot be written. With
34//! [`SerializerConfig::set_canonical`] map entries are sorted to produce a
35//! deterministic encoding.
36//!
37//! Deserialization accepts all well-formed MessagePack. Map keys can be of
38//! any type. Signed integers that are not negative are passed on as
39//! `U64`, negative integers as `I64`. Extensions are passed on as
40//! extension atoms: timestamps as [`Timestamp`], all others as [`Ext`] whose
41//! fallback is the binary data. Strings are validated as UTF-8.
42//!
43//! [`Timestamp`]: deser_core::ext::Timestamp
44//!
45//! # Raw Values
46//!
47//! [`RawMsgpack`] holds the MessagePack encoding of a value. The encoding
48//! of values that are deserialized from MessagePack is kept as it is: it's
49//! validated but not deserialized, and written out again unchanged unless
50//! canonical output is requested. Values of other formats are encoded as
51//! MessagePack.
52//!
53//! ```rust
54//! use deser_msgpack::RawMsgpack;
55//!
56//! #[derive(deser::Deserialize, deser::Serialize)]
57//! struct Record {
58//! id: u32,
59//! payload: RawMsgpack<'static>,
60//! }
61//!
62//! // {"id": 1, "payload": [1, 2]} with 1 encoded as uint 8
63//! let input = [
64//! 0x82, 0xa2, b'i', b'd', 0x01, 0xa7, b'p', b'a', b'y', b'l', b'o',
65//! b'a', b'd', 0x92, 0xcc, 0x01, 0x02,
66//! ];
67//! let record: Record = deser_msgpack::from_slice(&input).unwrap();
68//! assert_eq!(record.payload.as_bytes(), [0x92, 0xcc, 0x01, 0x02]);
69//! assert_eq!(record.payload.deserialize::<Vec<u32>>().unwrap(), [1, 2]);
70//! assert_eq!(deser_msgpack::to_vec(&record).unwrap(), input);
71//! ```
72//!
73//! See [`Raw`](deser_core::ext::Raw) for more information.
74//!
75//! # Features
76//!
77//! * `io` (enabled by default): reading and writing streams of the
78//! standard library, see [streams](#streams). Requires `std`.
79//! * `speedups` (enabled by default): validates UTF-8 with [`simdutf8`](https://docs.rs/simdutf8).
80//! * `std` (enabled by default): uses the standard library. Without it
81//! this crate only needs `alloc` (see [`no_std`](https://docs.rs/deser/latest/deser/#no_std)).
82//!
83//! # Streams
84//!
85//! Items are read from a [`Read`](std::io::Read) with [`from_reader`] and
86//! written to a [`Write`](std::io::Write) with [`to_writer`]. To read or
87//! write items that follow each other (for instance on a socket) the
88//! configurations create readers and writers of
89//! [`deser::io`](deser_core::io) ([`DeserializerConfig::reader`] and
90//! [`SerializerConfig::writer`]). The reader only buffers until an item is
91//! complete:
92//!
93//! ```rust
94//! # #[cfg(feature = "io")] {
95//! use deser_msgpack::{DeserializerConfig, SerializerConfig};
96//!
97//! let mut writer = SerializerConfig::new().writer(Vec::new());
98//! writer.write(&vec![1u32, 2]).unwrap();
99//! writer.write(&"three").unwrap();
100//! let bytes = writer.into_inner();
101//!
102//! let mut reader = DeserializerConfig::new().reader(&bytes[..]);
103//! assert_eq!(reader.read::<Vec<u32>>().unwrap(), Some(vec![1, 2]));
104//! assert_eq!(reader.read::<String>().unwrap().as_deref(), Some("three"));
105//! assert_eq!(reader.read::<String>().unwrap(), None);
106//! # }
107//! ```
108//!
109//! The stream serializer ([`Serializer`]) and the stream deserializer
110//! ([`StreamDeserializer`]) do not do IO themselves (see
111//! [`deser::stream`](deser_core::stream)), they also work with other kinds
112//! of IO (for instance async runtimes with `deser-tokio`) and without the
113//! standard library.
114#![doc(html_logo_url = "https://raw.githubusercontent.com/mitsuhiko/deser/main/artwork/logo.svg")]
115#![cfg_attr(not(any(feature = "std", test)), no_std)]
116
117extern crate alloc;
118
119mod copy;
120mod de;
121mod ext;
122mod head;
123mod parser;
124mod raw;
125mod ser;
126mod stream;
127
128pub use self::de::{Deserializer, DeserializerConfig, DeserializerConfigBuilder, Iter, from_slice};
129pub use self::ext::Ext;
130pub use self::raw::{Msgpack, RawMsgpack};
131#[cfg(feature = "io")]
132pub use self::ser::to_writer;
133pub use self::ser::{Serializer, SerializerConfig, SerializerConfigBuilder, to_vec};
134pub use self::stream::StreamDeserializer;
135#[cfg(feature = "io")]
136pub use self::stream::from_reader;