serde_smile/
lib.rs

1//! A Smile implementation for Serde.
2//!
3//! [Smile] is a binary data format created by the developers of the Jackson serialization library for Java. It is
4//! designed to be a binary equivalent of JSON.
5//!
6//! # Serialization Options
7//!
8//! Smile defines several optional features that can be enabled or disabled during serialization:
9//!
10//! * [`Builder::raw_binary`]: If enabled, binary data will be encoded directly as "raw" bytes, rather than using
11//!   Smile's 7-bit "safe" encoding. The raw format is 14% smaller and faster to serialize and deserialize, but usage
12//!   means that encoded values may contain Smile control characters such as the end-of-stream token `0xff`. Disabled
13//!   by default.
14//! * [`Builder::shared_strings`]: If enabled, string values 64 bytes and smaller will be deduplicated in the encoded
15//!   format. This increases the memory overhead of serialization and deserialization, but can significantly shrink
16//!   the size of the encoded value when strings are repeated. Disabled by default.
17//! * [`Builder::shared_properties`]: If enabled, map keys will be deduplicated in the encoded format. This increases
18//!   the memory overhead of serialization and deserialization, but can significantly shrink the size of the encoded
19//!   value when keys are repeated (particularly struct field names). Enabled by default.
20//! * [`Serializer::end`]: A sequence of Smile values can optionally be terminated by the end-of-stream token `0xff`.
21//!   Calling this method will write the token into the output stream.
22//!
23//! # Special Types
24//!
25//! Smile supports two kinds of values that Serde does not natively handle: arbitrary precision integers and decimals.
26//! This crate defines special types [`BigInteger`] and [`BigDecimal`] which will serialize to and deserialize from
27//! their respective Smile types. However, they should only be used with the serializers and deserializers defined
28//! within this crate as they will produce nonsensical values when used with other Serde libraries.
29//!
30//! # Encoding Notes
31//!
32//! Rust integer values that cannot be stored in an `i64` will be serialized as Smile `BigInteger` values. In the other
33//! direction, `BigInteger` values will be deserialized to Rust integer types if the value is small enough.
34//!
35//! # Examples
36//!
37//! Serialize a Rust object into a Smile value:
38//! ```rust
39//! use serde::Serialize;
40//! use serde_smile::Error;
41//!
42//! #[derive(Serialize)]
43//! struct Address {
44//!     number: u32,
45//!     street: String,
46//! }
47//!
48//! fn main() -> Result<(), Error> {
49//!     let address = Address {
50//!         number: 1600,
51//!         street: "Pennsylvania Avenue".to_string(),
52//!     };
53//!
54//!     let value = serde_smile::to_vec(&address)?;
55//!
56//!     Ok(())
57//! }
58//! ```
59//!
60//! Deserialize a Smile value into a Rust object:
61//! ```rust
62//! use serde::Deserialize;
63//! use serde_smile::Error;
64//!
65//! #[derive(Deserialize)]
66//! struct Address {
67//!     number: u32,
68//!     street: String,
69//! }
70//!
71//! fn main() -> Result<(), Error> {
72//!     let smile = b":)\n\x01\xfa\x85number\x24\x32\x80\x85street\x52Pennsylvania Avenue\xfb";
73//!
74//!     let address: Address = serde_smile::from_slice(smile)?;
75//!
76//!     println!("{} {}", address.number, address.street);
77//!
78//!     Ok(())
79//! }
80//! ```
81//!
82//! [Smile]: https://github.com/FasterXML/smile-format-specification
83//! [`Builder::raw_binary`]: ser::Builder::raw_binary
84//! [`Builder::shared_strings`]: ser::Builder::shared_strings
85//! [`Builder::shared_properties`]: ser::Builder::shared_properties
86//! [`BigInteger`]: value::BigInteger
87//! [`BigDecimal`]: value::BigDecimal
88#![warn(missing_docs)]
89
90#[doc(inline)]
91pub use de::{from_mut_slice, from_reader, from_slice, Deserializer};
92#[doc(inline)]
93pub use error::Error;
94#[doc(inline)]
95pub use ser::{to_vec, to_writer, Serializer};
96
97pub mod de;
98mod error;
99pub mod ser;
100#[cfg(test)]
101mod test;
102pub mod value;
serde_smile/lib.rs

serde_smile/
lib.rs
